---
title: Find & Replace
icon: TextSearch
---

<MetaData
  lang="en-US"
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-find-replace',
      locale: '@univerjs/preset-sheets-find-replace/locales/en-US',
      style: '@univerjs/preset-sheets-find-replace/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs/find-replace',
      locale: '@univerjs/find-replace/locale/en-US',
      style: '@univerjs/find-replace/lib/index.css',
    }, {
      client: '@univerjs/sheets-find-replace',
      facade: '@univerjs/sheets-find-replace/facade',
      locale: '@univerjs/sheets-find-replace/locale/en-US',
    }],
    server: 'No',
  }}
/>

The Find & Replace feature allows users to quickly search for specific content in spreadsheets and replace it, supporting various matching options to help users efficiently process data.

<PlaygroundFrame lang="en-US" slug="sheets/find-replace" clickToShow />

## Preset Mode

### Installation

```package-install
npm install @univerjs/preset-sheets-find-replace
```

### Usage

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsFindReplacePreset } from '@univerjs/preset-sheets-find-replace' // [!code ++]
import UniverPresetSheetsFindReplaceEnUS from '@univerjs/preset-sheets-find-replace/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-find-replace/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsFindReplaceEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsFindReplacePreset(), // [!code ++]
  ],
})
```

## Plugin Mode

### Installation

```package-install
npm install @univerjs/find-replace @univerjs/sheets-find-replace
```

### Usage

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverFindReplacePlugin } from '@univerjs/find-replace' // [!code ++]
import FindReplaceEnUS from '@univerjs/find-replace/locale/en-US' // [!code ++]
import { UniverSheetsFindReplacePlugin } from '@univerjs/sheets-find-replace' // [!code ++]
import SheetsFindReplaceEnUS from '@univerjs/sheets-find-replace/locale/en-US' // [!code ++]

import '@univerjs/find-replace/lib/index.css' // [!code ++]

import '@univerjs/sheets-find-replace/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      FindReplaceEnUS, // [!code ++]
      SheetsFindReplaceEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverFindReplacePlugin) // [!code ++]
univer.registerPlugin(UniverSheetsFindReplacePlugin) // [!code ++]
```

## Facade API

Complete Facade API type definitions can be found in the [FacadeAPI](https://reference.univer.ai/en-US).

### Create Text Finder

`univerAPI.createTextFinderAsync()` creates a text finder and returns an `FTextFinder` instance.

Here are some member methods on [`FTextFinder`](https://reference.univer.ai/en-US/classes/FTextFinder):

| Method | Description |
| ------ | ----------- |
| findAll | Get all the matched cells of the current sheet, the current matched cell is the last matched cell |
| findNext | Get the next matched cell of the current sheet, if exists return the next matched cell and move the current matched cell to the next matched cell |
| findPrevious | Get the previous matched cell of the current sheet, if exists return the previous matched cell and move the current matched cell to the previous matched cell |
| getCurrentMatch | Get the current matched cell of the current sheet |
| matchCaseAsync | Set the match case option, if true, the find operation will match case, otherwise, the find operation will ignore case |
| matchEntireCellAsync | Set the match entire cell option, if true, the find operation will match entire cell value, otherwise, the find operation will match part of the cell value |
| matchFormulaTextAsync | Set the match formula text option, if true, the find operation will match formula text, otherwise, the find operation will match value |
| replaceAllWithAsync | Replace all the matched text with the given text |
| replaceWithAsync | Replace the current matched text with the given text |
| ensureCompleteAsync | Ensure the find operation is completed. Especially when the current sheet changed use this method to ensure the find operation is completed |

```typescript
// Assume the current sheet is empty sheet.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set some values to the range A1:D10.
const fRange = fWorksheet.getRange('A1:D10')
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13],
])

// Create a text-finder to find the text '5'.
const textFinder = await univerAPI.createTextFinderAsync('5')

// Find all cells that contain the text '5'.
const matchCells = textFinder.findAll()
matchCells.forEach((cell) => {
  cell.getA1Notation() // D2, C3, B4, A5
})
```
